<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="embroot.css">
<TITLE>
Passing Control and Data to ECLiPSe from C
</TITLE>
</HEAD>
<BODY >
<A HREF="embroot080.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot073.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="embroot082.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc146">C.8</A>&nbsp;&nbsp;Passing Control and Data to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> from C</H2>
These are the functions needed to embed ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> into C code.
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>void		ec_post_goal(const pword)</B><DD CLASS="dd-description"><BR>
	post a goal (constraint) that will be executed when ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>	is resumed.<BR>
<BR>
<DT CLASS="dt-description"><B>void		ec_post_string(const char *)</B><DD CLASS="dd-description"><BR>
	same as ec_post_goal(), but the goal is given in ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> syntax
	in a string. This should only be used if speed is not critical
	and if the goal does not contain variables whose values may be
	needed later.
	This function is part of the simplified interface.<BR>
<BR>
<DT CLASS="dt-description"><B>void		ec_post_exdr(int len, const char *exdr)</B><DD CLASS="dd-description"><BR>
	same as ec_post_goal(), but the goal is given in EXDR format
	(see chapter <A HREF="embroot049.html#chapexdr">9</A>).
	This function is part of the simplified interface.<BR>
<BR>
<DT CLASS="dt-description"><B>int		ec_resume()</B><DD CLASS="dd-description"><BR>
	resume execution of the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engine: All posted goals will
	be executed and all posted events will be handled.
	The return value will be PSUCCEED if the goals succeed
	PFAIL is returned if the goals fail, and PYIELD if control was
	yielded because of a
	<A HREF="../bips/kernel/externals/yield-2.html"><B>yield/2</B></A><A NAME="@default392"></A>
	predicate call in the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> code.
	If a writable queue stream with yield-option
	(see <A HREF="../bips/kernel/iostream/open-4.html"><B>open/4</B></A><A NAME="@default393"></A>)
	was flushed, the return value is PFLUSHIO.
	If there was an attempt to read from an empty queue stream with
	yield-option, the return value is PWAITIO.
	If an asynchronous ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> thread is already running,
	PRUNNING is returned.
	No parameters can be passed.
	This function is part of the simplified interface.<BR>
<BR>
<DT CLASS="dt-description"><B>int		ec_resume1(ec_ref ToC)</B><DD CLASS="dd-description"><BR>
	Similar to ec_resume(), but if the return value is PSUCCED,
	the ToC argument returns a cut value that can be used to discard
	alternative solutions by passing it to ec_cut_to_chp().
	If the return value is PYIELD, control was yielded because of a
	<A HREF="../bips/kernel/externals/yield-2.html"><B>yield/2</B></A><A NAME="@default394"></A>
	predicate call in the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> code, and ToC contains the data
	passed by the first argument of
	<A HREF="../bips/kernel/externals/yield-2.html"><B>yield/2</B></A><A NAME="@default395"></A>.
	If the return value is PFLUSHIO or PWAITIO, ToC contains
	the associated stream number.<BR>
<BR>
<DT CLASS="dt-description"><B>int		ec_resume2(const pword FromC,ec_ref ToC)</B><DD CLASS="dd-description"><BR>
	Similar to ec_resume1(), but it allows to pass an argument
	to the resumed execution. This is only useful if the execution
	had yielded due to a
	<A HREF="../bips/kernel/externals/yield-2.html"><B>yield/2</B></A><A NAME="@default396"></A>
	predicate call. The term FromC is passed as input into the
	second argument of
	<A HREF="../bips/kernel/externals/yield-2.html"><B>yield/2</B></A><A NAME="@default397"></A>.<BR>
<BR>
<DT CLASS="dt-description"><B>int		ec_resume_long(long *ToC)</B><DD CLASS="dd-description"><BR>
	Similar to ec_resume1(), but allows only integer values to be passed
	from ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> to C (otherwise TYPE_ERROR is returned).
	This function is part of the simplified interface.<BR>
<BR>
<DT CLASS="dt-description"><B>int		ec_resume_async()</B><DD CLASS="dd-description"><BR>
	Similar to ec_resume(), but ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> is resumed in a separate
	thread in case this is supported by the operating system.
	The return value is PSUCCED if the thread started successfully,
	SYS_ERROR if there was a problem creating the thread, and
	PRUNNING if there was already an ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> thread running
	(only one ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> thread is allowed to run at any time).
	If threads are not supported, the call does nothing and return
	PSUCCED. Use ec_resume_status() to wait for termination and
	to retrieve the results of the execution.<BR>
<BR>
<DT CLASS="dt-description"><B>int		ec_resume_status()</B><DD CLASS="dd-description"><BR>
	This function is supposed to be called after a call to
	ec_resume_async(). It returns PRUNNING as long as the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
	thread is still running. If the thread has stopped, the return
	values are the same as for ec_resume().
	If threads are not supported, the pair of ec_resume_async()
	and ec_resume_status() is equivalent to an ec_resume().<BR>
<BR>
<DT CLASS="dt-description"><B>int		ec_resume_status_long(long *ToC)</B><DD CLASS="dd-description"><BR>
	Similar to ec_resume_status(), but allows an integer to be
	returned to the caller, as done by ec_resume_long().<BR>
<BR>
<DT CLASS="dt-description"><B>int		ec_wait_resume_status_long(long *ToC, int timeout)</B><DD CLASS="dd-description"><BR>
	Similar to ec_resume_status_long(), but waits for the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> thread
	to finish execution. The function returns as soon as the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> thread
	is finished, or after timeout milliseconds, whatever is earlier.
	In case of timeout, the return value will be PRUNNING. If timeout is
	zero, the function is equivalent to ec_resume_status_long().
	If timeout is negative, there will be no timeout and the function
	will only return when the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> thread is finished.<BR>
<BR>
<DT CLASS="dt-description"><B>int		ec_handle_events(long *ToC)</B><DD CLASS="dd-description"><BR>
	Similar to ec_resume_long(), but posted goals are not executed,
	only events are handled.<BR>
<BR>
<DT CLASS="dt-description"><B>void		ec_cut_to_chp(ec_ref)</B><DD CLASS="dd-description"><BR>
	Cut all choicepoints created by the batch of goals whose execution
	succeeded. The argument should have been obtained by a call to
	ec_resume2().<BR>
<BR>
<DT CLASS="dt-description"><B>int		ec_post_event(pword Name)</B><DD CLASS="dd-description"><BR>
	Post an event to the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engine. This will lead to the
	execution of the corresponding event handler once the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>	execution is resumed. See also <A HREF="../bips/kernel/event/event-1.html"><B>event/1</B></A><A NAME="@default398"></A> and the User Manual
	chapter on event handling for more information.
	Name should be an ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> atom.<BR>
<BR>
<DT CLASS="dt-description"><B>int		ec_post_event_string(const char *)</B><DD CLASS="dd-description"><BR>
	Post an event to the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> engine. This will lead to the
	execution of the corresponding event handler once the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>	execution is resumed. See also <A HREF="../bips/kernel/event/event-1.html"><B>event/1</B></A><A NAME="@default399"></A> and the User Manual
	chapter on event handling for more information. The event name
	is given as a string.
	This function is part of the simplified interface.
</DL>
<HR>
<A HREF="embroot080.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot073.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="embroot082.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
